
#ifndef __CE_ASSET_ASSETLOCATOR_H__
#define __CE_ASSET_ASSETLOCATOR_H__

#include <export.h>
#include <string>


/**
 * @brief The ceAssetLocator class
 *
 * All assets within the \a CrimsonCore system can be located by an instance
 * of this class. The locator provides a tuple <tt>(name, location)</tt> to find the
 * data within the (virtual) filesystem.
 *
 * E.g. the name of a texture is <b>'textures/grounds/bumpy_metal.tex'</b>. At first:
 * that is simply a name, not specifying anything where to find that file. If not
 * specified otherwise the name of the asset is also the location. So the name
 * maps to the filesystem filename <b>'<tt>${VFS_ROOT}</tt>/textures/grounds/bumpy_metal.tex'</b>.
 *
 * The system is capable of having bundled files. That are files containing more than
 * one entry. This is for example a commong way having a single file 'textures/textures.tex'
 * which contains one entry for every texture definition.
 *
 * @code
 * texture <grounds/beach_stones>
 * {
 *		filename <textures/grounds/beach_stones.jpg>
 * }
 * texture <grounds/green_grass>
 * {
 *    filename <textures/grounds/green_grass.jpg>
 * }
 * @endcode
 *
 * By that one could specify to look for an asset name <b>'grounds/green_grass'</b> within the file
 * <b>'textures/textures.tex'</b> which in turns is located at <b>'<tt>${VFS_ROOT}</tt>/textures/textures.tex'</b>.
 *
 * So for those to examples one would write the following to locators.
 *
 * @code
 * ceAssetLocator locBumpyMetal ("textures/grounds/bumpy_metal.tex");
 * ceAssetLocator locBeachStones  ("grounds/beach_stones", "textures/textures.tex");
 * @endcode
 *
 * It is up to the ceAssetSystem to really open those files and find a propper iAssetReader
 * for reading them
 *
 *
 */
class CE_API ceAssetLocator
{
	friend class ceAsset;
private:
	std::string	_name;
	std::string	_location;

	ceAssetLocator ();
public:

	/**
	 * @brief Constructor for creating an immutable asset location.
	 *
	 * If no location is given, it is assumed, that the default naming conventions
	 * are taken place and the full quallyfied name contains the filename.
	 *
	 * @param name The name of the asset
	 * @param location [optional] The location where the asset is located.
	 */
	ceAssetLocator (const char* name, const char* location = 0);

	/**
	 * @brief Returns the name of the asset.
	 *
	 * @return The name of the asset
	 */
	const char* GetName () const;

	/**
	 * @brief Returns the location where the asset resides.
	 *
	 * If there was no location given during construction time
	 * this method will return the name of the asset
	 *
	 * @return The location where the asset resides.
	 */
	const char* GetLocation () const;
};

#endif /* ! __CE_ASSET_ASSETLOCATOR_H__ */

